---
title: XDesignXElement
summary: API reference for XDesignXElement.
status: draft
owner: SAIF Documentation
last_reviewed: 2026-08-21
library: SAIF.Services.Printing
reference_type: embedded
---

# XDesignXElement

`XDesignXElement` is the core xPression XML builder in this library: it extends `SAIFXElement` with a key/
foreign-key model so that nested repeating sections in a report's data tree carry the parent context xPression
needs, and it owns the recursive rendering (`ToXpression`) that turns the tree into the escaped, indented
xPression XML dialect consumed by `clsPrint.previewDocument` and `distributeDocument`.

## Purpose
- Track primary keys (`AddKey`) and inherited foreign keys (`ForeignKeys`) on each element so nested repeating
  sections can be correlated back to their parent rows
- Propagate keys down the tree on the first (top-level) `ToXpression` call
  ([BR-PRT-016](../../business-rules.md#br-prt-016-key-propagation-for-nested-repeating-sections))
- Render leaf elements as escaped text or self-closing tags when empty
  ([BR-PRT-017](../../business-rules.md#br-prt-017-empty-value-self-closing-elements), [BR-PRT-018](../../business-rules.md#br-prt-018-xml-value-escaping))
- Render container elements with their inherited foreign keys followed by their children, recursively

## Context
- Namespace: `SAIF.Services.Printing.Reporting`
- Assembly/package: `SAIF.Services.Printing` (embedded library, project reference)
- Base class: `SAIFXElement` (`SAIF.Framework.Common` package)

## Public members
| Member | Signature | Purpose |
| --- | --- | --- |
| `Keys` | `Public ReadOnly Property Keys As Dictionary(Of String, String)` | Primary keys registered on this element via `AddKey` |
| `ForeignKeys` | `Public ReadOnly Property ForeignKeys As Dictionary(Of String, String)` | Foreign keys this element inherited from an ancestor during key propagation |
| `AddKey` | `Public Sub AddKey(name As String, value As String)` | Registers a primary key on this element for propagation to descendants |
| `Clone` | `Public Function Clone() As XDesignXElement` | Returns a copy of this element (including its keys) |
| `ToXpression` | `Public Function ToXpression(tabIndex As Integer) As String` | Renders this element (and, recursively, its descendants) into the xPression XML dialect; runs `PropagateKeys` when `tabIndex = 0` ([BR-PRT-016](../../business-rules.md#br-prt-016-key-propagation-for-nested-repeating-sections)) |
| `DisplayKeys` | `Public Function DisplayKeys(tabIndex As Integer) As String` | Renders this element's keys/foreign keys for diagnostic display |

## Behavioral notes
- On the top-level `ToXpression(0)` call, `PropagateKeys` recursively walks child `XDesignXElement`s, clears
  their foreign keys, and for each child that itself has children, copies the parent's primary keys and
  inherited foreign keys down as that child's foreign keys ([BR-PRT-016](../../business-rules.md#br-prt-016-key-propagation-for-nested-repeating-sections)).*
- A leaf element (no child elements) renders as `<Name>escaped value</Name>`, or `<Name/>` when the value is
  empty ([BR-PRT-017](../../business-rules.md#br-prt-017-empty-value-self-closing-elements)); values are escaped with `System.Security.SecurityElement.Escape`
  ([BR-PRT-018](../../business-rules.md#br-prt-018-xml-value-escaping)).
- A container element renders a start tag, then all inherited foreign keys as elements, then each child
  (recursively, at `tabIndex + 1`; a plain `XElement` child is first lifted via `Extensions.ToSAIFXElement`),
  then the end tag; indentation is two spaces per level.
- Private members `PropagateKeys`, `RenderStartElement`, `RenderEndElement`, and `RenderElement` implement the
  behaviors above but are not part of the public surface.

## Constraints and usage notes
- Callers must call `AddKey` on parent elements before the top-level `ToXpression(0)` call, since key
  propagation happens once, at the start of rendering.

> **Note:** Statements marked with * were inferred from code structure, naming conventions, or
> contextual evidence where direct confirmation was not available in source artifacts.

## Sources
- SAIF.Services.Printing/Reporting/XDesignXElement.vb